---
title: 数据库和文本处理工具 | Kastrax 文档
description: Kastrax 提供的数据库工具和文本处理工具详细指南，包括配置、使用方法和最佳实践。
---

# 数据库和文本处理工具 ✅

Kastrax 提供了强大的数据库工具和文本处理工具，使代理能够与数据库交互并执行文本操作。本指南详细介绍这些工具的使用方法和最佳实践。

## 数据库工具 ✅

数据库工具允许代理与各种数据库系统交互，执行查询和更新操作。

### 创建数据库工具

使用 `ToolFactory` 创建数据库工具：

```kotlin
import ai.kastrax.core.tools.ToolFactory
import ai.kastrax.core.agent.agent
import ai.kastrax.integrations.deepseek.deepSeek
import ai.kastrax.integrations.deepseek.DeepSeekModel
import kotlinx.coroutines.runBlocking
import javax.sql.DataSource
import org.postgresql.ds.PGSimpleDataSource

fun main() = runBlocking {
    // 创建数据源
    val dataSource = PGSimpleDataSource().apply {
        setURL("jdbc:postgresql://localhost:5432/mydatabase")
        user = "username"
        password = "password"
    }

    // 创建使用数据库工具的代理
    val myAgent = agent {
        name = "数据库助手"
        description = "一个可以与数据库交互的助手"
        
        // 配置 LLM
        model = deepSeek {
            apiKey = "your-deepseek-api-key"
            model = DeepSeekModel.DEEPSEEK_CHAT
            temperature = 0.7
        }
        
        tools {
            // 添加数据库工具
            add(ToolFactory.createDatabaseTool(dataSource))
        }
    }
    
    // 使用代理
    val response = myAgent.generate("列出数据库中的所有用户")
    println(response.text)
}
```

### 支持的数据库类型

数据库工具支持多种数据库系统：

1. **PostgreSQL**：高级开源关系型数据库
2. **MySQL**：流行的开源关系型数据库
3. **SQLite**：轻量级文件数据库
4. **MongoDB**：文档型 NoSQL 数据库
5. **其他 JDBC 兼容数据库**：通过 JDBC 驱动支持

### 数据库工具参数

数据库工具支持以下参数：

| 参数 | 类型 | 描述 | 是否必需 |
|------|------|------|----------|
| `operation` | String | 操作类型（query, update, batch, getTables, getColumns） | 是 |
| `sql` | String | SQL 查询或更新语句 | 对于 query/update/batch 操作是必需的 |
| `params` | Map<String, Any> | 查询参数 | 否 |
| `table` | String | 表名 | 对于 getColumns 操作是必需的 |
| `limit` | Int | 结果限制 | 否 |

### 使用示例

#### 执行查询

```kotlin
// 执行查询
val queryResult = databaseTool.execute(buildJsonObject {
    put("operation", "query")
    put("sql", "SELECT * FROM users WHERE age > ?")
    putJsonObject("params") {
        put("1", 18) // 参数索引从 1 开始
    }
    put("limit", 10)
})
```

#### 执行更新

```kotlin
// 执行更新
val updateResult = databaseTool.execute(buildJsonObject {
    put("operation", "update")
    put("sql", "UPDATE users SET name = ? WHERE id = ?")
    putJsonObject("params") {
        put("1", "张三")
        put("2", 1)
    }
})
```

#### 获取表结构

```kotlin
// 获取表结构
val tablesResult = databaseTool.execute(buildJsonObject {
    put("operation", "getTables")
})

// 获取列信息
val columnsResult = databaseTool.execute(buildJsonObject {
    put("operation", "getColumns")
    put("table", "users")
})
```

### MongoDB 操作

对于 MongoDB 数据库，工具支持特定的操作：

```kotlin
// 查找文档
val findResult = mongoTool.execute(buildJsonObject {
    put("operation", "find")
    put("collection", "users")
    putJsonObject("filter") {
        putJsonObject("age") {
            put("$gt", 18)
        }
    }
    put("limit", 10)
})

// 插入文档
val insertResult = mongoTool.execute(buildJsonObject {
    put("operation", "insertOne")
    put("collection", "users")
    putJsonObject("document") {
        put("name", "张三")
        put("age", 25)
        put("email", "zhangsan@example.com")
    }
})
```

### 安全注意事项

使用数据库工具时，请注意以下安全事项：

1. **限制数据库权限**：为代理使用的数据库用户分配最小权限
2. **使用参数化查询**：始终使用参数化查询防止 SQL 注入
3. **限制查询结果**：设置合理的结果限制，防止返回过多数据
4. **敏感数据保护**：避免查询和返回敏感数据
5. **审计日志**：记录所有数据库操作，便于审计和排查问题

## 文本处理工具 ✅

文本处理工具提供了一系列文本操作功能，使代理能够执行各种文本转换和分析。

### 创建文本处理工具

使用 `SimpleToolFactory` 创建文本处理工具：

```kotlin
import ai.kastrax.core.tools.SimpleToolFactory
import ai.kastrax.core.agent.agent
import ai.kastrax.integrations.deepseek.deepSeek
import ai.kastrax.integrations.deepseek.DeepSeekModel
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // 创建使用文本处理工具的代理
    val myAgent = agent {
        name = "文本助手"
        description = "一个可以处理文本的助手"
        
        // 配置 LLM
        model = deepSeek {
            apiKey = "your-deepseek-api-key"
            model = DeepSeekModel.DEEPSEEK_CHAT
            temperature = 0.7
        }
        
        tools {
            // 添加文本处理工具
            add(SimpleToolFactory.createTextProcessingTool())
        }
    }
    
    // 使用代理
    val response = myAgent.generate("将'hello world'转换为大写")
    println(response.text)
}
```

### 文本处理工具参数

文本处理工具支持以下参数：

| 参数 | 类型 | 描述 | 是否必需 |
|------|------|------|----------|
| `operation` | String | 操作类型（uppercase, lowercase, reverse, length, match, replace） | 是 |
| `text` | String | 要处理的文本 | 是 |
| `pattern` | String | 正则表达式模式（用于 match 和 replace 操作） | 对于 match/replace 操作是必需的 |
| `replacement` | String | 替换文本（用于 replace 操作） | 对于 replace 操作是必需的 |

### 支持的操作

文本处理工具支持以下操作：

1. **uppercase**：将文本转换为大写
2. **lowercase**：将文本转换为小写
3. **reverse**：反转文本
4. **length**：计算文本长度
5. **match**：使用正则表达式匹配文本
6. **replace**：使用正则表达式替换文本

### 使用示例

#### 基本文本操作

```kotlin
// 转换为大写
val uppercaseResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "uppercase")
    put("text", "hello world")
})

// 转换为小写
val lowercaseResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "lowercase")
    put("text", "HELLO WORLD")
})

// 反转文本
val reverseResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "reverse")
    put("text", "hello world")
})

// 计算长度
val lengthResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "length")
    put("text", "hello world")
})
```

#### 正则表达式操作

```kotlin
// 匹配文本
val matchResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "match")
    put("text", "联系我：zhangsan@example.com 或 13800138000")
    put("pattern", "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b")
})

// 替换文本
val replaceResult = textProcessingTool.execute(buildJsonObject {
    put("operation", "replace")
    put("text", "联系我：zhangsan@example.com 或 13800138000")
    put("pattern", "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b")
    put("replacement", "[电子邮件已隐藏]")
})
```

### 自定义文本处理工具

您可以创建自定义的文本处理工具，添加特定的文本处理功能：

```kotlin
import ai.kastrax.core.tools.tool
import kotlinx.coroutines.runBlocking

// 创建自定义文本处理工具
val customTextTool = tool("customTextProcessor") {
    description("执行自定义文本处理")
    
    parameters {
        parameter("text", "要处理的文本", String::class)
        parameter("operation", "操作类型", String::class)
    }
    
    execute { params ->
        val text = params["text"] as String
        val operation = params["operation"] as String
        
        when (operation) {
            "wordCount" -> {
                val words = text.split(Regex("\\s+")).filter { it.isNotEmpty() }
                "文本包含 ${words.size} 个单词"
            }
            "sentenceCount" -> {
                val sentences = text.split(Regex("[.!?。！？]+")).filter { it.isNotEmpty() }
                "文本包含 ${sentences.size} 个句子"
            }
            "characterFrequency" -> {
                val frequency = text.groupBy { it }.mapValues { it.value.size }
                frequency.entries.sortedByDescending { it.value }
                    .take(5)
                    .joinToString(", ") { "${it.key}: ${it.value}" }
            }
            else -> "不支持的操作: $operation"
        }
    }
}
```

## 组合使用数据库和文本处理工具 ✅

数据库工具和文本处理工具可以组合使用，实现更复杂的功能：

```kotlin
import ai.kastrax.core.tools.ToolFactory
import ai.kastrax.core.tools.SimpleToolFactory
import ai.kastrax.core.agent.agent
import ai.kastrax.integrations.deepseek.deepSeek
import ai.kastrax.integrations.deepseek.DeepSeekModel
import kotlinx.coroutines.runBlocking
import javax.sql.DataSource
import org.postgresql.ds.PGSimpleDataSource

fun main() = runBlocking {
    // 创建数据源
    val dataSource = PGSimpleDataSource().apply {
        setURL("jdbc:postgresql://localhost:5432/mydatabase")
        user = "username"
        password = "password"
    }
    
    // 创建使用多个工具的代理
    val myAgent = agent {
        name = "数据分析助手"
        description = "一个可以查询和分析数据的助手"
        
        // 配置 LLM
        model = deepSeek {
            apiKey = "your-deepseek-api-key"
            model = DeepSeekModel.DEEPSEEK_CHAT
            temperature = 0.7
        }
        
        tools {
            // 添加数据库工具
            add(ToolFactory.createDatabaseTool(dataSource))
            
            // 添加文本处理工具
            add(SimpleToolFactory.createTextProcessingTool())
        }
    }
    
    // 使用代理
    val response = myAgent.generate("查询所有用户的电子邮件地址并隐藏域名部分")
    println(response.text)
}
```

## 最佳实践 ✅

### 数据库工具最佳实践

1. **连接池管理**：使用连接池管理数据库连接，提高性能
2. **事务管理**：对于多步骤操作，使用事务确保数据一致性
3. **错误处理**：妥善处理数据库错误，提供有意义的错误消息
4. **性能优化**：优化查询，添加适当的索引，限制结果集大小
5. **数据验证**：在执行更新操作前验证输入数据

### 文本处理工具最佳实践

1. **大文本处理**：对于大文本，考虑分块处理，避免内存问题
2. **正则表达式优化**：优化正则表达式，避免回溯问题
3. **国际化支持**：确保工具正确处理各种语言和字符集
4. **错误处理**：妥善处理文本处理错误，提供有意义的错误消息
5. **缓存结果**：对于重复的文本处理操作，考虑缓存结果

## 总结 ✅

数据库工具和文本处理工具是 Kastrax 中强大的功能，使代理能够与数据库交互并执行各种文本操作。通过遵循本指南中的最佳实践和安全注意事项，您可以安全地使用这些工具，创建功能强大的代理应用程序。
